05 nextjs env 환경변수 사용법 | ✅ 편저: 코담 운영자

📦 Next.js에서 .env, .env.local 등 환경변수 사용법

Next.js에서는 환경변수 파일을 통해 다양한 실행 환경(개발/운영 등)에서 설정 값을 다르게 관리할 수 있습니다. 아래는 사용 가능한 환경변수 파일들과 그 역할을 정리한 내용입니다.

---

✅ 사용 가능한 환경변수 파일 종류

파일명	설명	Git에 커밋?
.env	기본 환경변수 파일 (모든 환경 공통)	⭕ 예 (공통 설정만)
.env.local	로컬 개발용 개인 설정	❌ 보통 .gitignore 처리
.env.development	개발 서버 실행 시(next dev) 적용	⭕
.env.production	프로덕션 빌드 시(next build) 적용	⭕
.env.test	테스트 환경용	⭕

우선순위: .env.local > .env.[environment] > .env

📌 참고: .env.prod 형식으로 환경변수 파일을 작성하는 경우도 있으나, Next.js는 공식적으로 .env.production 등의 파일명을 인식합니다. .env.prod는 자동으로 로딩되지 않으며, 사용하려면 커스텀 로직으로 직접 불러와야 합니다.

---

🔒 환경변수 선언 방법

# 예: .env.local 또는 .env
NEXT_PUBLIC_API_URL=https://api.example.com
SECRET_API_KEY=abcdefg123456

• NEXT_PUBLIC_ 접두사가 붙은 변수만 브라우저에서 접근 가능
• 그 외 변수는 서버사이드 전용 (노출되지 않음)

---

💻 사용 예시

1. Next.js 코드에서 사용

// 브라우저에서도 접근 가능
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// 서버사이드에서만 사용 가능
const secretKey = process.env.SECRET_API_KEY;

2. 터미널에서 환경 지정 실행 예

NODE_ENV=production next build && NODE_ENV=production next start

또는 package.json의 script에 지정 가능:

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "NODE_ENV=production next start"
}

⚠️ pnpm start 혹은 npm start 명령은 단순히 start 스크립트를 실행할 뿐이며, **자동으로 **``을 인식하지 않습니다. 반드시 NODE_ENV=production을 명시하거나, 서버 실행 전에 환경을 지정해주어야 합니다.

---

✳️ 참고: next dev 시 자동 동작

• next dev 또는 pnpm dev를 실행하면 NODE_ENV=development가 자동 설정됨
• 따라서 .env.local > .env.development > .env 순서로 환경변수를 자동으로 읽음
• 별도로 NODE_ENV=development를 명시하거나 .env.local을 직접 지정할 필요 없음

---

🛠 기타 설정 팁

• .env.local은 팀원마다 다른 값 (예: API 키, DB 주소 등) 저장용
• Git에 커밋하면 안 되는 민감 정보는 .env.local에 넣고 .gitignore에 추가
• 환경변수 수정 후 서버 재시작 필수 (Next.js는 재시작해야 적용됨)

---

✅ .gitignore 예시

.env.local
.env.*.local

---

🧪 예제 구조

my-next-app/
├── .env
├── .env.local          # ← 개인 개발 설정 (Git에 제외)
├── .env.development    # ← dev 전용
├── .env.production     # ← prod 전용
└── next.config.js

---

📌 정리

• NEXT_PUBLIC_ 붙이면 클라이언트에서 접근 가능
• .env.local은 개인 개발환경 전용, 커밋 금지
• 환경변수 설정 변경 시, Next 서버를 반드시 재시작
• 사용 순위: .env.local > .env.[env] > .env
• pnpm start 시 .env.production을 자동 인식하지 않으므로 NODE_ENV를 명시해야 함
• pnpm dev 시에는 NODE_ENV=development이 자동 적용되므로 별도 설정 없이 .env.local을 인식함
• .env.prod는 Next.js에서 자동으로 인식되지 않으므로 사용 시 주의 필요

필요 시 next.config.js에서 커스텀 환경 설정도 가능!